You have made phoneNumber required, but the network subscriber will also be identified by a 3-legged access token (this will be the usual method of calling this API according to CAMARA guidelines). Can you explain the API logic when both a 3-legged token and explicit phoneNumber are received?

@eric-murray
Because we assume that this API uses 2-legged access token.
As the user story mentioned, ASP checks whether there has been a change in the user associated with the phone number after the specified date so that API can ensure that a phone number is correctly linked to an user and prevent mis-delivery before sending SMS messages to an wrong user (if there has been a change).
If we apply 3-legged access token, we cannot use this API. Because ASP may authenticate the wrong user and potentially may ask for the wrong user's consent for the API access with 3-legged access token.

Hi @yamamoto0104
This is not compliant with ICM requirements, which state:

... in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory

In Europe, for example, end users have the right to opt-out from such anti-fraud APIs processing their data, and hence 3-legged tokens are mandatory. We cannot say to an end user that their legal rights no longer apply just because they might be a fraudster.

Exactly the same situation arises with the SIM Swap API, which does (indeed, must) allow 3-legged tokens. The implementations I am aware of only support CIBA, which does not require any interaction with the end user device itself. The same would apply here.

Hello @eric-murray
Thank for your comment.

As the description in SIM Swap API yaml file said, 2-legged access tokens can be applicable as one of the options.
If my understanding is incorrect, please let me know.

Restrictions for tokens without an associated authenticated phone number:

• For scenarios which do not have a phone number associated to the token during the authentication flow, e.g. 2-legged access tokens, the phoneNumber field MUST be provided in the API request. This ensures that the phone number is explicit and valid for each API call made with these tokens.

Hi @yamamoto0104

Indeed, if the SIM Swap API is called with a 2-legged access token, then phoneNumber must be provided. But if it is called with a 3-legged token, then a phoneNumber MUST NOT be provided. So the phoneNumber is not a required parameter. This can be seen from the SIM Swap CreateCheckSimSwap schema.

In your proposed API definition, phoneNumber is always a required parameter. So the API consumer would be forced to provide it, irrespective of whether at 2- or 3-legged token was being used.

Hi @eric-murray
Thank you for your kind response.
We changed phoneNumber as optional and added the phone number description based on SIM-SWAP yaml file.

Hi @eric-murray

We updated the phone number description based on the Appendix of API design guidelines. We also added 422 error code based on the Appendix.

Appendix A: info.description template for device identification from access token

Thanks, The version was changed.

A common PhoneNumber schema has been defined by Commonalities, so we should use it here

Thanks for pointing it out. We added the common PhoneNumber schema.

Reference separate schema

Thanks. Reference separate schema is added.